Workers v1
The import/workers endpoints allows you to import the workers properties.
Authorisation
A function key is required. The name of Key must match Software Key
Request format
Method and URL
The HTTP method and URL is as follows:
HTTP
POST https://payandbill-cloud-api.azurewebsites.net/api/import/workers?version=1
Request Headers
| Name | Type | Description |
|---|---|---|
| header | X-Functions-Key | Function Api Key |
| header | X-Software-Key | Software Key for this Integration |
Request Body
| Name | Type | Description |
|---|---|---|
| body | Workers[] | Workers schema |
Request Body Example
Example Request Body
[
{
"EmployerRef": "ER1",
"PersonnelRef": "WORKER1",
"Surname": "Worker",
"FirstForename": "Sample",
"SecondForename": "MiddleName",
"ThirdForename": "Third Forename",
"Title": "Mr",
"KnownAs": "SampleWorker",
"WorkerAddress": {
"AddressLine1": "First Line of Address",
"AddressLine2": "Second Line of Address",
"AddressLine3": "Third Line of Address",
"AddressLine4": "Fourth Line of Address",
"AddressLine5": "Fifth Line of Address",
"Postcode": "PC1",
"Country": "UK"
},
"TelephoneNumber": "0123456789",
"Gender": 0,
"DateOfBirth": "1970-01-01T00:00:00",
"MaritalStatus": "Unknown",
"PreviousSurname": "PreviousName",
"Nationality": "British",
"Citizenship": "UK",
"PassportHeld": "Full",
"NextOfKin": "Next Of Kin Name",
"NextOfKinRelation": "Brother",
"NextOfKinAddress": {
"AddressLine1": "First Line of NOK Address",
"AddressLine2": "Second Line of NOK Address",
"AddressLine3": "Third Line of NOK Address",
"AddressLine4": "Fourth Line of NOK Address",
"AddressLine5": "Fifth Line of NOK Address",
"Postcode": "PC3",
"Country": "UK"
},
"NextOfKinTelephone": "032134567",
"EmergencyContact": "Emergency Contact",
"EmergencyContactTelephone": "0123456789",
"LastAddress": {
"AddressLine1": "First Line of Last Address",
"AddressLine2": "Second Line of Last Address",
"AddressLine3": "Third Line of Last Address",
"AddressLine4": "Fourth Line of Last Address",
"AddressLine5": "Fifth Line of Last Address",
"Postcode": "PC2",
"Country": "UK"
},
"StartDate": "2021-01-01T00:00:00",
"LeavingDate": "2020-01-01T00:00:00",
"LeavingCode": "LEAVE",
"UserIndex": "USR1",
"PersonnelNotes": "Personnel Notes",
"WorkTelephone": "0123456789",
"WorkFax": "0123456789",
"MobileTelephone": "0770123456",
"PrimaryEmailAddress": "primary@sampledata.co.uk",
"SecondaryEmailAddress": "secondary@sampledata.co.uk",
"PrimaryPayMethod": "BACS",
"SecondaryPayMethod": "BACS",
"PrimaryBankDetails": {
"BankAccountType": 0,
"BankRef": "Bank Ref",
"BuildingSocietyName": "Build Soc Name",
"BuildingSocietyNumber": "123456789",
"BankSortCode": "123456",
"BankAccountNumber": "1234567789",
"BankAccountName": "Bank Account Name",
"IBAN": "IBAN",
"BIC": "BIC"
},
"SecondaryBankDetails": {
"BankAccountType": 0,
"BankRef": "Bank Ref 2",
"BuildingSocietyName": "Build Soc Name",
"BuildingSocietyNumber": "123456789",
"BankSortCode": "654321",
"BankAccountNumber": "987654321",
"BankAccountName": "Secondary Bank Account Name",
"IBAN": "IBAN 2",
"BIC": "BIC 2"
},
"PayrollNotes": "Payroll Notes",
"IsStudent": false,
"AnalysisCode": "Analysis1",
"DivisionRef": "DIV1",
"DepartmentRef": "DEPT1",
"JobCategoryRef": "JOB1",
"EmploymentType": "PAYE",
"CurrencyRef": "GBP",
"ConsultantRef": "CONS1",
"PayslipPrintMethod": "Electronic",
"IsWorkerAlertedBySMS": false,
"IsWorkerAlertedByEmail": false,
"PassportNumber": "123456789",
"AnalysisCode3": "Analysis3",
"AnalysisCode4": "Analysis4",
"AnalysisCode5": "Analysis5",
"IsExpat": false,
"ExternalWorkerRef": "EXT1",
"EIREngagementStatus": "PAYE",
"IsApprentice": false,
"eP45PrintMethod": "Electronic",
"IsExcludedFromWTR": false,
"HasOnlineAccess": true,
"STITemplate": "Worker",
"STIUserRef": "SampleWorkerLogin",
"UKPayrollDetails": {
"NINumber": "AB123456",
"NITableLetter": "A",
"IsContractedOut": false,
"PAYECode": "NT",
"PAYEMethod": 1,
"TaxRegime": "None",
"IsExcludedFromRegPension": false,
"StartingDecCategory": "A",
"HasStudentLoan": true,
"StartingDecByEmployee": true,
"OptIn": false,
"StudentLoanPlanType": "01",
"IsStudentFinishedStudies": true,
"IsStudentLoanPaidExternally": false,
"HasPostgradLoan": false,
"PostgradLoanPlanType": "PG",
"IsPostgradFinishedStudies": true,
"IsPostgradLoanPaidExternally": false
}
}
]
Responses
| Name | Type | Description |
|---|---|---|
| 200 Ok | Results[] | successful operation |
| 400 Bad Request | string | Invalid Json request or Invalid DB Version |
| 401 Unauthorized | string | Invalid/Missing API Key |
| 403 Forbidden | string | Key name does not match Software Key |
| 403 Forbidden | string | Integration missing for Software Key or disabled |
| 403 Forbidden | string | Pay and Bill Database not active |
| 501 Not Implemented | string | Message Type not found/implemented |
| 501 Not Implemented | string | Payload data not supported |
Response Example
Example Response
{
"results": [
{
"recordIds": [
{
"field": "TimesheetNumber",
"value": "000005355"
}
],
"importStatus": "OK",
"errorCount": 0,
"warningCount": 0,
"infoCount": 0
}
]
}
400 Response
Response when Invalid Json Request Body is sent to API.
Message will contain parsing error message.
400 Error Response
{
"message": "<string>"
}
200 Response
A results array is returned which will include an item for each array item in the original request body.
Each item will identify the recordId's relevant for this message type.
Import Status, errorCount & warningCount will indicate the status of that row.
Messages will contain any error/warning messages relevant.
Note: Each row is treated as a separate commit to the database, so if multiple items are included in the import, the response will indicate which have been imported successfully & which have failed to import.
200 Ok Response
{ "results": [
{
"recordIds": [
"field": "<string>",
"value": "<string>"
],
"importStatus": "<string>",
"errorCount": <number>,
"warningCount": <number>,
"messages": [
{
"messageType": "<string>",
"message": "<string>",
"fieldName": "<string>"
}
]
}
]
}
Results
This is the response output from the import/workers endpoint
| Property | Type | Defined |
|---|---|---|
| RecordIds | recordIds[] | Workers Results |
| ImportStatus | string | Workers Results |
| ErrorCount | integer | Workers Results |
| WarningCount | integer | Workers Results |
| InfoCount | integer | Workers Results |
| Messages | messages[] | Workers Results |
RecordIds
A record id of the imported Workers
RecordIds
- Type:
array
| Property | Type | Defined |
|---|---|---|
| Field | string | Workers Results |
| Value | string | Workers Results |
Example
{
"recordIds": [
{
"field": "EmployerRef",
"value": "1308"
},
{
"field": "PersonnelRef",
"value": "503"
}
]
}
ImportStatus
The import status of the request
ImportStatus
Type:
stringdefined in: Workers Results
ErrorCount
Number of errors in the request
ErrorCount
Type:
integerdefined in: Workers Results
WarningCount
Number of warnings in the request
WarningCount
Type:
integerdefined in: Workers Results
InfoCount
Number of Information messages in the request
InfoCount
Type:
integerdefined in: Workers Results
Messages
An output of the info, warning or error messages.
Messages
- Type:
array
| Property | Type | Defined |
|---|---|---|
| MessageType | string | Workers Results |
| Message | string | Workers Results |
| FieldName | string | Workers Results |
| FieldValue | string | Workers Results |
| ErrorId | integer | Workers Results |
Example
{
"messages": [
{
"messageType": "Error",
"message": "Worker already exists in the system",
"fieldName": "WorkerNumber",
"fieldValue": "000005354",
"errorID": 10000
}
]
}